/* ========================================================================= */
/* ------------------------------------------------------------------------- */
/*!
  \file			idrawfile.h
  \date			Jun 2012
  \author		TNick

  \brief		Contains the definition for IDrawFile class


*//*


 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Please read COPYING and README files in root folder
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*/
/* ------------------------------------------------------------------------- */
/* ========================================================================= */
#ifndef __IDRAWFILE_INC__
#define __IDRAWFILE_INC__
//
//
//
//
/*  INCLUDES    ------------------------------------------------------------ */

#include	<cpg/cpg.h>

#include	<QMap>
#include	<QList>
#include	<usermsg.h>
#include	<memtrack.h>
#include	<version3d.h>
#include	<bytebuffer.h>

/*  INCLUDES    ============================================================ */
//
//
//
//
/*  CLASS    --------------------------------------------------------------- */

class	QFile;
class	QTemporaryFile;

namespace	BBlocks		{

class	UserMsg;

}


namespace	cpg		{

class	CpgDoc;

/**
*	@brief	Interface class for dealing with files
*/
class CPGSHARED_EXPORT IDrawFile		: public MemTrack		{
	BBM_TRACK( IDrawFile );

	//
	//
	//
	//
	/*  DEFINITIONS    ----------------------------------------------------- */


	/**
	*	@brief	description of the callback used with tags
	*/
	typedef		void			(*kbTagHandler)		(
			IDrawFile *				f_format,
			BBlocks::Version3D		version,
			const QString &			tag,
			void *					opaq_data,
			BBlocks::UserMsg &		um
			);


	/**
	*	@brief	class that maps tags to callbacks
	*/
	typedef	QMap<QString,kbTagHandler>		TagMap;


	/*  DEFINITIONS    ===================================================== */
	//
	//
	//
	//
	/*  DATA    ------------------------------------------------------------ */

private:


	/**
	*	@brief	tag handlers
	*/
	TagMap			handlers_;


	/*  DATA    ============================================================ */
	//
	//
	//
	//
	/*  FUNCTIONS    ------------------------------------------------------- */

public:


	/**
	*	@brief	constructor;
	*/
	IDrawFile			( void );


	/**
	*	@brief	destructor;
	*/
	virtual				~IDrawFile		( void );


protected:


	/**
	*	@brief	inheritants may use to read the files
	*/
	bool				readToBA		(
			const QString &				s_file,
			BBlocks::ByteBuffer &		out,
			BBlocks::UserMsg &			um
			);


	/**
	*	@brief	inheritants may use to write the files
	*/
	bool				writeFromBA		(
			const QString &				s_file,
			BBlocks::ByteBuffer &		out,
			BBlocks::UserMsg &			um
			);




	/* ******************************************************************* */
	/** @name 	Tags related functionality                                 */
	/* ******************************************************************* */
	///@{


public:


	/**
	*	@brief	set the callback associated with a particular tag
	*
	*	If there is a callback already associated with this tag it wil be
	*	overwritten.
	*/
	inline void			setTag				(
			const QString &				s_tag,
			kbTagHandler				handler
			)
	{
		handlers_[ s_tag.toUpper() ] = handler;
	}


	/**
	*	@brief	sremoves apecified tag
	*/
	inline void			remTag				(
			const QString &				s_tag
			)
	{
		handlers_.remove( s_tag );
	}


	/**
	*	@brief	get the callback associated with a particular tag
	*/
	inline kbTagHandler	getTagCallback		(
			const QString &				s_tag
			)
	{
		return handlers_[ s_tag.toUpper() ];
	}


protected:


	/**
	*	@brief	get a temporary file to store opaque data
	*
	*	@param	s_src_file	the file that is being opened by the IDrawFile
	*	@param	um			eror corellation
	*/
	QTemporaryFile *	getTempOpaq				(
			const QString &		s_src_file,
			BBlocks::UserMsg &	um
			);


	///@}
	/* ******************************************************************* */





	/* ******************************************************************* */
	/** @name 	Methods that inheritants may implement                     */
	/* ******************************************************************* */
	///@{


public:


	/**
	*	@brief	load the content from provided file content
	*/
	virtual bool				load				(
			CpgDoc *						dest_doc,
			BBlocks::ByteBuffer &		p_data,
			BBlocks::UserMsg &			um
			)
	{
		Q_UNUSED( dest_doc );
		Q_UNUSED( p_data );
		um.add( BBlocks::UserMsgMgr::MSG_ERROR, QObject::tr(
					"%1 file format does not support loading from a memory buffer." )
				.arg( name() )
				);
		return false;
	}


	/**
	*	@brief	load the content from provided file
	*/
	virtual bool				load				(
			CpgDoc *						dest_doc,
			const QString &				file_path,
			BBlocks::UserMsg &			um
			)
	{
		Q_UNUSED( dest_doc );
		Q_UNUSED( file_path );
		um.add( BBlocks::UserMsgMgr::MSG_ERROR, QObject::tr(
					"%1 format does not support loading from a file." )
				.arg( name() )
				);
		return false;
	}


	/**
	*	@brief	save the drawing using this format to a file
	*/
	virtual bool				save				(
			CpgDoc *						doc,
			const QString &				file_path,
			BBlocks::Version3D			version,
			BBlocks::UserMsg &			um
			)
	{
		Q_UNUSED( doc );
		Q_UNUSED( file_path );
		Q_UNUSED( version );
		um.add( BBlocks::UserMsgMgr::MSG_ERROR, QObject::tr(
					"%1 file format does not support saving to a file." )
				.arg( name() )
				);
		return false;
	}


	/**
	*	@brief	save the drawing using this format to a data buffer
	*/
	virtual bool				save				(
			CpgDoc *						doc,
			BBlocks::ByteBuffer &		p_data,
			BBlocks::Version3D			version,
			BBlocks::UserMsg &			um
			)
	{
		Q_UNUSED( doc );
		Q_UNUSED( version );
		Q_UNUSED( p_data );
		um.add( BBlocks::UserMsgMgr::MSG_ERROR, QObject::tr(
					"%1 file format does not support saving to memory buffers." )
				.arg( name() )
				);
		return false;
	}


	///@}
	/* ******************************************************************* */



	/* ******************************************************************* */
	/** @name 	Methods that inheritants MUST implement                    */
	/* ******************************************************************* */
	///@{


	/**
	*	@brief	the extension string to be used with QFileDialog::getOpenFileName()
	*/
	virtual QString				getExtDec			( void ) = 0;


	/**
	*	@brief	tell if this (uppercase) expression is an accepted extension
	*/
	virtual bool				isThisYours			(
			const QString &				s_ext
			) = 0;


	/**
	*	@brief	tell if the content is recognised as a file we can handle
	*/
	virtual bool				isThisYours			(
			BBlocks::ByteBuffer &		p_data
			) = 0;


	/**
	*	@brief	a short name for this format - plain text
	*/
	virtual QString				name				( void ) = 0;


	/**
	*	@brief	a description for this format in html
	*/
	virtual QString				description			( void ) = 0;


	///@}
	/* ******************************************************************* */



	/*  FUNCTIONS    ======================================================= */
	//
	//
	//
	//

};	/*	class IDrawFile	*/

/*  CLASS    =============================================================== */
//
//
//
//

}	//	namespace	cpg

#endif // __IDRAWFILE_INC__
/* ------------------------------------------------------------------------- */
/* ========================================================================= */
